 Copyright (c) 2005, 2012, Oracle and/or its affiliates. All rights reserved. 



             Oracle Multimedia Java Servlet Sample Application
             =================================================


This file describes the steps required to build and run the Oracle Multimedia
Java Servlet Photo Album sample application. This sample application is 
available after you install the Oracle Database Examples media, which 
you can download from Oracle Technology Network (OTN).

=============================================================================
Note: 

For simplicity in demonstrating this feature, this example does not perform
the password management techniques that a deployed system normally uses. In a
production environment, follow the Oracle Database password management
guidelines, and disable any sample accounts. See Oracle Database Security
Guide for password management guidelines and other security recommendations. 
=============================================================================

Contents
========

    About the Java Servlet Sample Application
    Configuring Your Servlet Container
        For Oracle Fusion Middleware 10gR3 Application Server 
            Requirements
            Setting up and Building the Sample Application
    Running the Java Servlet Sample Application
    Removing the Java Servlet Sample Application


About the Java Servlet Sample Application
=========================================

The Oracle Multimedia Java Servlet Photo Album sample application shows 
how to use the Oracle Multimedia Servlets and JSP Java class library to 
upload and retrieve multimedia data to and from a database. Users can 
access the servlet to view the contents of the photo album (including 
thumbnail versions of each photograph), to view the full-size version of 
any photograph, and to upload new photographs into the album.

PhotoAlbumServlet.java contains two classes, PhotoAlbumServlet and
PhotoAlbumRequest. The PhotoAlbumServlet class responds to GET and
POST requests by allocating a JDBC connection from a connection pool,
creating an instance of the PhotoAlbumRequest class to execute the
request, executing the request, and releasing the JDBC connection back
to the pool at the end of the request. Each HTTP GET or POST request 
is assigned its own JDBC connection from the pool to ensure that 
multiple requests can be serviced concurrently.

In the PhotoAlbumRequest class, the viewDBInfoForm() method displays 
an HTML form that prompts users to enter the database user name, the 
password and the connection string. The application uses this information 
to connect to the database, and to retrieve and upload photographs.

Users can choose one of these options for the database connection string:

    Option 1. A JDBC OCI driver specifying a SQL*Net service name.
       This option works on all platforms where an Oracle Database
       client is installed.  

    Option 2. A JDBC Thin driver specifying a host, port and Oracle 
       Database SID. This option works on all platforms and does not 
       require an Oracle Database client. 

The viewAlbum() method displays the contents of photo album using 
the tag <IMG SRC="<servlet-path>?media=..."> to display the thumbnail 
images. The viewPhoto() method, which displays the full-size version 
of a photograph, uses the tag <IMG SRC="<url>"> to display an image.  
Both URLs in the <IMG> tag cause the viewMedia() method to be invoked 
to retrieve an image from the database and deliver it to the browser 
using the OrdHttpResponseHandler class. The viewUploadForm() method 
displays an HTML form that allows users to upload new photos. 
The insertNewPhoto() method uses the OrdHttpUploadFormData class to 
parse a multipart/form-data POST request containing an uploaded photograph, 
and uses the OrdHttpUploadFile class to upload the new photograph 
into the database.


Configuring Your Servlet Container
==================================
This section describes how to configure your servlet container. 


For Oracle Fusion Middleware 10gR3 Application Server 
=====================================================

Requirements
------------
This software must be installed to run the Oracle Multimedia Java
Servlet Photo Album sample application:

. Oracle Database with Oracle Multimedia.  

. Oracle Fusion Middleware 10gR3 Application Server (Oracle WebLogic Server 10.3)

Setting up and Building the Sample Application
----------------------------------------------
In these instructions, <ORACLE_HOME> represents the Oracle Database home 
directory, and <BEA_HOME> represents the default installation home 
directory for the Oracle Fusion Middleware Application Server(Oracle 
WebLogic Server 10.3). Choose the appropriate home directory based on 
your specific installation, then follow these steps.

1) Choose a database schema under which you want to create the photo
   album table and the sequence. 

2) Create the photo album table and the sequence:

    The Oracle Multimedia JavaServer Pages photo album sample application
    uses a sequence and this table definition:

      Name                  Null?     Type
      --------------------  --------  ----------------------------

      ID                    NOT NULL  NUMBER
      DESCRIPTION           NOT NULL  VARCHAR2(40)
      LOCATION                        VARCHAR2(40)
      IMAGE                           ORDSYS.ORDIMAGE
      THUMB                           ORDSYS.ORDIMAGE


    a. Start SQL*Plus and connect to the database with your user 
       name and password

       ->  SQL> connect <USER>[@<SERVICE>]
           Enter password: <password>

    b. Create the photo album table and sequence: 

       ->  SQL> @photostab.sql

3) Compile the photo album sample application servlet:

    PhotoAlbumServlet.java depends on these java class libraries: 

    a. The Oracle Multimedia Servlets and JSP Java class library
       (ordhttp.jar) and the Oracle Multimedia Java classes library
       (ordim.jar), which are installed with Oracle Multimedia in the
       directory  <ORACLE_HOME>/ord/jlib.

    b. The JDBC library and Java Servlet library that are installed 
       with Oracle Fusion Middleware Application Server.

    You can set these libraries to the CLASSPATH environment variables, 
    or specify them in the command line. For example: 

   [on Linux/UNIX]
->  <BEA_HOME>/jdk160_05/bin/javac -d . -classpath .:<ORACLE_HOME>/ord/jlib/ordim.jar:<ORACLE_HOME>/ord/jlib/ordhttp.jar:<BEA_HOME>/wlserver_103/server/lib/ojdbc6.jar:<BEA_HOME>/modules/javax.servlet_1.0.0.0_2-5.jar PhotoAlbumServet.java

   [on Windows]
->  <BEA_HOME>\jdk160_05\bin\javac -d . -classpath .;<ORACLE_HOME>\ord\jlib\ordim.jar;<ORACLE_HOME>\ord\jlib\ordhttp.jar;<BEA_HOME>\wlserver_103\server\lib\ojdbc6.jar;<BEA_HOME>\modules\javax.servlet_1.0.0.0_2-5.jar PhotoAlbumServet.java

    Note: 

    To avoid compatibility issues, use the JDK installed with the
    Oracle Fusion Middleware Application Server. 

    PhotoAlbumServlet.java contains two classes: 
    PhotoAlbumServlet and PhotoAlbumRequest. Thus, compiling 
    PhotoAlbumServlet.java produces two class files.

4) Copy the resulting Java class files and the Oracle Multimedia 
   libraries to a directory that is enabled to run servlets. 

   a. Copy the PhotoAlbumServlet.class and PhotoAlbumRequest.class  
      files into this directory: 

      [on Linux/UNIX]
      <BEA_HOME>/wlserver_10.3/samples/server/examples/build/mainWebApp/WEB-INF/classes 

      [on Windows]
      <BEA_HOME>\wlserver_10.3\samples\server\examples\build\mainWebApp\WEB-INF\classes
        
   b. Copy these Oracle Multimedia class libraries 

      [on Linux/UNIX]
        <ORACLE_HOME>/ord/jlib/ordhttp.jar
        <ORACLE_HOME>/ord/jlib/ordim.jar
 
      [on Windows]
        <ORACLE_HOME>\ord\jlib\ordhttp.jar
        <ORACLE_HOME>\ord\jlib\ordim.jar
 
   c. Place the copies in this directory (if it does not exist create it): 

      [on Linux/UNIX]
        <BEA_HOME>/wlserver_10.3/samples/server/examples/build/mainWebApp/WEB-INF/lib/ 
      [on Windows]
        <BEA_HOME>\wlserver_10.3\samples\server\examples\build\mainWebApp\WEB-INF\lib\

5) Create the directory "images" and copy the file image error_qualifier.png to 
   the directory. 

   a. If the directory "images" does not exist, create it in this location:  

   [on Linux/UNIX]
     <BEA_HOME>/wlserver_10.3/samples/server/examples/build/mainWebApp/ 

   [on Windows]
     <BEA_HOME>\wlserver_10.3\samples\server\examples\build\mainWebApp\

   b. Copy the file error_qualifier.png into the "images" directory.

6) Add servlet configuration to the file WEB-INF/web.xml.
  
   <servlet>
      <servlet-name>PhotoAlbumServlet</servlet-name> 
      <servlet-class>PhotoAlbumServlet</servlet-class> 
   </servlet>
   <servlet-mapping>
      <servlet-name>PhotoAlbumServlet</servlet-name> 
      <url-pattern>/servlet/PhotoAlbumServlet</url-pattern> 
   </servlet-mapping>

7) Restart the servlet container or the web server if you made any changes. 


Running the Java Servlet Sample Application
===========================================
To use the sample application, enter the URL of the servlet in the location 
bar of your web browser. For example:

  http://<HOST:PORT>/servlet/PhotoAlbumServlet

When first called, the servlet displays an HTML form to prompts 
users to enter a database user name, password and a connection string 
in this form: 

   JDBC thin driver
   jdbc:oracle:thin:@<host>:<port>:<sid> 

   JDBC OCI driver
   jdbc:oracle:oci:@ 

After you click the submit, the application displays the photo album. 
The photo album displays the information for each image that is stored 
in the album with a thumbnail image. 

To upload a new photograph, click "Upload new photo". Then, enter 
a description of the photograph, the location where it was taken, 
and the name of the image file. Click "Upload new photo" to view the 
contents of the photo album, including the new photograph. 

Click on a thumbnail image to view the full-size version of any photograph. 
The servlet displays the text "[view image]" instead of a thumbnail 
image for images whose formats are not recognized by Oracle Multimedia. 

To connect to a different database or change the database 
schema, go back to the photo album page and click "Change schema". 

   
Removing the Java Servlet Sample Application
============================================
Use the script remove.sql to drop photo album schema objects from your 
database.

1)  Start SQL*Plus and connect to the database with your  user name 
    and password

    ->  SQL> connect <USER>[@<SERVICE>]
        Enter password: <password>

2)  Drop the photo album table and the sequence:

    ->  SQL> @remove.sql


=================
End of readme.txt
